---
id: docker
title: Install with Docker
description: Installation and deployment instructions for using Docker to deploy a Tracetest Agent and use the Cloud-based managed Tracetest Control Plane / Dashboard.
hide_table_of_contents: true
keywords:
  - tracetest
  - tracetest cli install
  - tracetest cloud install
  - tracetest agent install
  - trace-based testing
  - observability
  - distributed tracing
  - testing
image: https://res.cloudinary.com/djwdcmwdz/image/upload/v1698686403/docs/Blog_Thumbnail_14_rsvkmo.jpg
---

This guide explains how to install a Tracetest Agent in your Docker (and Docker Compose) environment. This deployment uses the Cloud-based managed Tracetest Control Plane and Dashboard.

## Prerequisites

- Install [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/).
- [Sign in to Tracetest](https://app.tracetest.io/) and retrieve your [Tracetest Organization API Key/Token and Environment ID](https://app.tracetest.io/retrieve-token).


## Install the Tracetest Agent with Docker

[Tracetest Agent](/concepts/agent) runs as a Docker container.

```bash title="Terminal"
docker run
  -p 4317:4317
  -p 4318:4318
  -e TRACETEST_API_KEY="<TRACETEST_API_KEY>"
  -e TRACETEST_ENVIRONMENT_ID="<TRACETEST_ENVIRONMENT_ID>"
  kubeshop/tracetest-agent
```

## Install the Tracetest Agent with Docker Compose

[Tracetest Agent](/concepts/agent) runs as a Docker Compose service.

```yaml title="docker-compose.yaml"
tracetest-agent:
  image: kubeshop/tracetest-agent
  environment:
    - TRACETEST_API_KEY=<TRACETEST_API_KEY>
    - TRACETEST_ENVIRONMENT_ID=<TRACETEST_ENVIRONMENT_ID>
  ports:
    - 4317:4317
    - 4318:4318
```

The Tracetest Agent is running in a Docker network and can run tests and ingest traces. It exposes OTLP ports `4317` (gRPC) and `4318` (HTTP) for trace ingestion. 

To ingest traces in this example with Tracetest Agent use these URLs:

- gRPC: `http://tracetest-agent:4317`
- HTTP: `http://tracetest-agent:4318/v1/traces`

:::note Docker Network
Running a test against `localhost` will resolve as `127.0.0.1` inside the Tracetest Agent container. Add Tracetest Agent to the same network and use service name mapping. *Example: Instead of running an app on `localhost:8080`, add it to your Docker Compose file, connect it to the same network as your Tracetest Agent service, and use `<service-name>:8080` in the URL field when creating a test.*

To run tests against apps running on your local machine, [view this guide](/install/cli).
:::